------------------------------------------------------------------------
API per la macchina della gestione aziendale di Tibet
versione 1.7.6 del 29/10/2009
------------------------------------------------------------------------

*******************************************************************************
Queste librerie sono compatibili solo con versioni di Tibet 1.7.6
*******************************************************************************


Le API sono fornite in forma di libreria dinamica "C language" creata con gcc (Mac OS) o Visual Studio (Windows):


Mac OS X
--------
mgacli7.framework	framework per runtime Mach-O
MgaCliLibcarbon7		Carbon shared library - wrapper
					(deve essere installato anche il framework)

Windows
-------
mgacli7.dll		per processori Intel
mgacli7.lib		stub library per la mgacli6.dll

Le "Application Program Interfaces" che accompagnano questo documento sono una prima versione *non definitiva*: permettono di accedere a tutti i dati del server Tibet, sia in lettura, sia in scrittura utilizzando direttamente il formato record interno di Tibet. In futuro saranno disponibili delle API che permetteranno di utilizzare delle liste campi in formato ASCII, evitando l'uso di un formato record fisso.

Le strutture corrispondenti al formato record dei vari archivi sono dichiarate nel file "tibetdic.st" e possono contenere quattro tipi di campi:

- Stringhe di caratteri (char, unsigned char)
- Date (Sy2Date)
- Numeri binari interi (short, long)
- Numeri binari con decimali a precisione fissa - detti Fixed - divisi in:
	Valori		(unsigned char [8])
	Quantita'	(unsigned char [6])
	Percentuali	(unsigned char [4])

I nomi delle strutture contengono l'identificativo dell'archivio (CARD_MGXX dove XX e' l'identificativo): ad esempio CARD_MGCF corrisponde all'archivio clienti-fornitori (vedi la lista degli identificativi nel documento Inf_Tecniche_Tibet.pdf sul CD-ROM)

<ftp://ftp.easybyte.it/pub/docs/note_tecniche/Inf_Tecniche_Tibet.pdf>

I tipi di variabile interni sono dichiarati nel file "sytypes.h".
Il file "pa_prmnt.h" contiene alcune definizioni utili per la gestione dell'archivio prima nota.


Per la lettura e la preparazione dei record saranno quindi necessari degli strumenti per convertire i campi di tipo Sy2Date e Fixed (formati interni di Tibet): nel programma che viene fornito con le API (mgaconsole.c) troverete degli esempi sull'utilizzo delle funzioni di conversione che sono fornite con le librerie.

Date
----

{
	Sy2Date unadata;
	char datastr[8];

	// per preparare un campo Sy2Date con la data 31/12/93
	Sy2StringToDate("311293", 6, 1, &unadata);

	// per convertire un campo Sy2Date in formato stringa
	Sy2DateToString(unadata, datastr, 0);
}

Fixed
-----

{
	unsigned char valore[VAL_FIX_LEN];
	char fixstr[32];

// per preparare un campo Fixed con il valore 10.000
// void BufToFixed(int fixlen, int decimals, int mode, char *s, int n, Sy2UBYTE *g);
	BufToFixed(VAL_FIX_LEN, 0, 0, "10000", strlen("10000"), valore);

// per convertire un campo Fixed in formato stringa
// int FixedToCString(int fixlen, Sy2UBYTE *fp, char *s, int maxlen);
	FixedToCString(VAL_FIX_LEN, valore, fixstr, sizeof(fixstr));

}

Insieme alle librerie troverete un programma di esempio (mgaconsole.c) che utilizza le API per collegarsi ad un server Tibet e permette di eseguire la consultazione degli archivi e l'inserimento di registrazioni di prima nota Generica ed IVA.

Troverete tutte le funzioni dichiarate nel file "mgaext.h" che dova' essere incluso nei vostri progetti.
Tutti i risultati tornati dalle funzioni sono zero o maggiori di zero se la chiamata e' andata a buon fine, negativi se si e' verificato un errore (il valore negativo e' il codice di errore - vedi il documento "lista_err.txt").

<ftp://ftp.easybyte.it/pub/docs/lista_err.txt>


-----------------------------------
API per MGA
-----------------------------------

int MGAExtOpenServices(int mode)
---------------------------------
Questa funzione deve essere chiamata prima di qualsiasi altra API e serve per allocare e inizializzare alcune variabili interne. Al termine della sessione di lavoro con le API di Tibet sara' necessario chiamare la funzione MGAExtCloseServices per rilasciare la memoria allocata. Il parametro mode deve essere sempre zero.


int MGACloseExternalServices(void)
----------------------------------
vedi la MGAExtOpenServices.


void MGAInit(MGACallBackProc mgacbp)
------------------------------------
Questa funzione permette di installare una procedura di callback per gestire alcune funzioni di interfaccia utente. Passando nil come callback, sara' utilizzata una callback interna di default.


int MGAClientGetConfPGM(void *cli_confpgmp, int confpgmlen)
-----------------------------------------------------------
La MGAClientGetConfPGM riempie il contenuto dell'area dati del primo parametro con la configurazione attuale del programma (CARD_CLCP). Se la lunghezza dell'area da assegnare e' diversa da sizeof(CARD_CLCP), viene tornato un errore e la configurazione del programma non viene assegnata.

int MGAClientSetConfPGM(void *cli_confpgmp, int confpgmlen)
-----------------------------------------------------------
La MGAClientSetConfPGM imposta la configurazione del programma "lato client". Il primo parametro deve essere un  puntatore ad una struttura di tipo CARD_CLCP. Se la lunghezza dell'area passata e' minore di sizeof(CARD_CLCP), viene tornato un errore e la configurazione del programma non viene impostata

int MGAClientValidateConfPGM(void *cli_confpgmp, int confpgmlen)
-----------------------------------------------------------------
La MGAClientValidateConfPGM controlla e convalida il contenuto dell'area dati del primo parametro che dovra' contenere la configurazione del programma (CARD_CLCP). E' opportuno eseguire questa chiamata in abbinamento alla MGAClientSetConfPGM prima di MGAStart per essere sicuri che il contenuto sia congruente con le possibili configurazioni del client di Tibet.


int MGAStart(int pgmtype, int key_num_pp, int flags)
----------------------------------------------------
Questa funzione esegue la vera e propria apertura della sessione di lavoro del client. Il parametro pgmtype sara' sempre uguale a 2, il parametro key_num_pp sara' uguale a zero e flags dovra' essere uguale a "MGARTFL_API_MODE" per informare MGA che il client non e' un Tibet client. A questa chiamata deve sempre corrispondere una MGAEnd per chiudere correttamente la connessione di rete.


void MGAEnd(void)
-----------------
Chiude la sessione di lavoro del client, aperta con MGAStart.


int MGAGetServerList(XNETLocalNameServerInfo *bcip, int max, int querytime, XNETQuerySpinProc spinproc, int mga_max_mp, int mga_tcp_offset, long par)
----------------------------------------------------------------------------------------------------------------------
Questa funzione ritorna il numero di server Tibet presenti nella rete locale. Il paramentro bcip deve essere fornito dall'utente ed e' un array di elementi XNETLocalNameServerInfo (definito in mgaclient.h) che verranno riempiti con i dati dei server trovati, max e' il numero massimo di server gestiti (la dimensione di bcip), querytime e' il numero di secondi massimo di attesa, spinproc e' una procedura di callback che sara' chiamata durante l'attesa e par e' un parametro a disposizione dell'utente che verra' passato alla callback spinproc. Il parametro mga_max_mp indica quanti server al massimo possono essere stati lanciati sullo stesso PC (normalmente MGA_TCP_MAX_MULTIPROGRAMS); Il parametro mga_tcp_offset indica l'intervallo (in termini di porte TCP) tra un server e l'altro (normalmente MGA_TCP_OFFSET_MULTIPROGRAMS).


void MGASetServer(XNETLocalNameServerInfo *bcip)
------------------------------------------------
Serve per impostare il server Tibet di riferimento. E' obbligatorio eseguire questa chiamata con una struttura XNETLocalNameServerInfo valida prima del login.


long MGAExtLogin(char *actkeyp)
-------------------------------
Esegue il login sul server di riferimento (previamente definito tramite la MGASetServer). Il parametro actkeyp deve essere un puntatore ad una chiave di attivazione valida ed abbinata al numero di serie del server (la chiave di attivazione e' quella di un Tibet Client). Nella maggior parte dei casi, dopo aver eseguito il login sara' necessario autenticare il client (via una MGAAuthenticateUser); l'autenticazione del client non e' necessaria solo nel caso in cui sul server siano stati disabilitati i permessi di accesso.
Dopo aver eseguito questa chiamata il client apparira' nella lista delle postazioni collegate sul server.


long MGAExtLoginToFirstServer(char *actkeyp, XNETQuerySpinProc spinproc, long par, unsigned short pgmtype, unsigned short pgmvers)
-------------------------------------------------------------------------------------------------------------------------
Questa funzione puo' sostituire le tre chiamate precedenti (MGAGetServerList, MGASetServer, MGAExtLogin) quando si e' certi dell'esistenza di un solo server sulla rete: equivale a richiedere il login sul primo server trovato sulla rete. Il parametro actkeyp actkeyp deve essere un puntatore ad una chiave di attivazione valida ed abbinata al numero di serie del server (la chiave di attivazione e' quella di un Tibet Client). I parametri spinproc e par hanno la stessa funzione di quelli della MGAGetServerList, il tempo di attesa e' sempre fisso ed uguale a 4 secondi.


void MGAExtLogout(void)
--------------------
Esegue il logout dal server Tibet. Deve sempre bilanciare una MGAExtLogin o MGAExtLoginToFirstServer al termine di una sessione di lavoro.


int MGANeedsUserName(void)
--------------------------
Questa funzione interroga il server sullo stato dei permessi si accesso: ritorna zero se i permessi di accesso sono attivati, ritorna MGA_TBPU_DISABLED se i permessi di accesso sono disattivati.


int MGAAuthenticateUser(char *username, char *passw, long *rec_idp)
-------------------------------------------------------------------
Esegue l'autenticazione del login. L'autenticazione e' necessaria per accedere a tutte le funzioni di MGA tranne che per la MGANeedsUserName. Il parametro username deve puntare ad un nome utente valido e deve essere normalizzato ad una lunghezza di 40 caratteri con blank come filler. Il parametro passw deve puntare alla parola chiave e deve essere normalizzato ad una lunghezza di 16 caratteri con blank come filler. Il parametro rec_idp, se diverso da nil, viene riempito con il recid dell'utente.


int MGAGetArchFromKey(long archname, long keyname, void *keyp, int keylen, void *bufp, int buflen)
--------------------------------------------------------------------------------------------------
Cerca la chiave puntata da "keyp" nell'indice "keyname" (1 se e' l'indice principale) dell'archivio "archname" (vedi Inf_Tecniche_Tibet.pdf). "keylen" e' la lunghezza della chiave puntata da "keyp". Se il risultato e' maggiore o uguale a zero il record puntato da "bufp" e' stato riempito con i dati della scheda corrispondente alla chiave trovata, altrimenti la chiave non e' stata trovata.


int MGAPutArchFromRecID(long name, long recn, void *bufp, int buflen)
---------------------------------------------------------------------
Scrive il record puntato da "bufp" nell'archivio "name" (vedi Inf_Tecniche_Tibet.pdf). Se "recn" e' uguale a zero il record viene aggiunto all'archivio, altrimenti il record "recn" viene modificato. Questa chiamat puo' essere utilizzata per scrivere dati in achivi "semplici" (i.e. non master/detail).

int MGAAddMasterDetail(long dbname, int variant, void *masterp, int masterlen, void *detailp, int detaillen, int numdetails, int checkonly)
-------------------------------------------------------------------------------------------------------------------------------------------
Aggiunge una scheda nell'archivio master/detail "dbname" (vedi Inf_Tecniche_Tibet.pdf). Il parametro "masterp" deve puntare alla struttura della testata (ad esempio CARD_MGDF * per i documenti fiscali); "detailp" deve puntare ad una array di "numdetails" righe (ad esempio CARD_MGRI * per i documenti fiscali). "masterlen" e "detaillen" sono le dimensioni in bytes rispettivamente di testata e una singola riga. Se il parametro "checkonly" e' diverso da zero, l'operazione viene simulata senza modificare l'archivio (ad esempio, per eseguire un import di controllo).
Il parametro variant e' sempre uguale a zero, tranne nel caso dell'archivio di prima nota (vedere mgaconsole.c per un esempio di scrittura nell'archivio prima nota)

==
L'insieme di chiamate MGAScanOpen/MGAScanNext/MGAScanClose devono essere utilizzate quando e' necessario leggere le schede di un archivio in sequenza (ad esempio per una stampa).
==
long MGAScanOpen(long dbname, long keyname)
long MGAScanArchOpen(long dbname, long keyname)
-----------------------------------------------
Questa funzione apre la scansione delle schede dell'archivio "dbname" (vedi Inf_Tecniche_Tibet.pdf) seguendo l'ordine della chiave "keyname" (1 se e' l'indice principale).
La variante MGAScanArchOpen deve essere utilizzata per gli archivi "composti", che oltre alla parte anagrafica contengono dei progressivi (ad esempio DBMG - articoli di magazzino): normalmente la MGAScanOpen esegue la lettura della sola parte anagrafica, utilizzando MGAScanArchOpen verranno letti anche i dati progressivi (l'operazione di lettura sara' leggermente piu' lenta).
Se l'apertura della scansione va a buon fine, la funzione torna il cosiddetto "sacnid" un valore maggiore di zero che dovra essere passato alla chiamate successive (MGAScanNext, MGAScanClose).

int MGAScanNext(long dbname, long scanid, void *bufp, int buflen);
int MGAScanArchNext(long dbname, long scanid, void *bufp, int buflen)
---------------------------------------------------------------------
Legge il prossimo record della scansione "scanid"; "dbname" e' l'archivio; "bufp" e' un puntatore alla struttura del record, verra' riempito con i dati letti; "buflen" e' la lunghezza in bytes del record.

long MGAScanClose(long scanid)
------------------------------
Chiude una scansione aperta con MGAScanOpen.


